Maps and scales a region within one rectangle to another rectangle.

void MapRgn (
     rgn, 
    const Rect *srcRect, 
    const Rect *dstRect
);

Parameter descriptions

rgn

A handle to a region. Upon input, this is the region to map. Upon completion, this region is the one mapped to a new location.

srcRect

The rectangle containing the region to map.

dstRect

The rectangle in which the new region will be mapped.

DISCUSSION

The MapRgn function takes a region within one rectangle and maps and scales it to another rectangle. In the rgn parameter, you specify a handle to a region that lies within the rectangle that you specify in the srcRect parameter. By calling the MapPt function to map all the points of the region in the rgn parameter, MapRgn maps and scales it to the rectangle that you specify in the dstRect parameter. The MapRgn function returns the result in the region whose handle you initially passed in the rgn parameter.

The MapRgn function is useful for determining whether a region operation will exceed available memory.  By mapping a large region into a smaller one and performing the operation (without actually drawing), you can estimate how much memory will be required by the anticipated operation.

SPECIAL CONSIDERATIONS

If the points or rectangles supplied to this function are defined in a graphics port other than your current graphics port, you must convert them to the local coordinate system of your current graphics port. You can accomplish this by using the SetPort function to change to the graphics port containing the points or rectangles, using the LocalGlobal function to convert their locations to global coordinates, using SetPort to return to your starting graphics port, and then using the GlobalToLocal function to convert the locations of points or rectangles to the local coordinates of your current graphics port.

The MapRgn function may move or purge memory blocks in the application heap; do not call this function at interrupt time.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.

© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)